---
description: Learn how to create a new board configuration in DeviceScript for
    supported chipset architectures.
sidebar_position: 10
keywords:
    - DeviceScript
    - board configuration
    - Visual Studio Code
    - command line
    - flash firmware
---

# Add Board

In DeviceScript, we commonly refere a Device Configuration as a `board`.
You can see examples of configuration in each device page ([like this one](/devices/esp32/seeed-xiao-esp32c3#configuration))

If your device is already using a supported system-on-a-chip (SoC) or MCU (ESP32, RP2040, ...),
you can create a new `board` configuration in your project to support it in DeviceScript.
You do **not** need to build a new firmware.

If you want to add a new system-on-a-chip (SoC), [follow the add Soc guide](/devices/add-soc).

:::tip

If you just need to reconfigure a couple pins, you can also use
the [configureHardware](/developer/board-configuration) function and skip the creation of a new board.

:::

## How to create a new board configuration

### Create the new `board.json` file

You will need three pieces of information to start a new board: (1) the existing configuration
you will fork, (2) a name and (3) an identifier.

In [Visual Studio Code](/getting-started/vscode),
select **DeviceScript: Add Board...** from the command palette.

Using the [Command Line](/getting-started/cli), use the `add board` command and follow the instructions.

```bash
devs add board
```

After this process, you wil have a new JSON under `/boards/`. The command line and
Visual Studio Code will automatically integrate any configuration files in the `/boards` folder.

### Editing the generated Device configuration (.json) file

The new configuration file is a schematized JSON file.
In Visual Studio Code, you will get tooltip, completion, syntax errors and auto-completion.

-   [ ] A new product identifier was automatically generated for you (but [you can regenerate a new one as well](https://microsoft.github.io/jacdac-docs/ddk/device-definition/)).

:::note

The product identifier is used to identify devices in the [Jacdac device catalog](https://microsoft.github.io/jacdac-docs/devices/)
which is leveraged by the simulator dashboard.

:::

-   [ ] configure the status light LED. DeviceScript supports monochrome LEDs, RGB LEDs,
        WS2812B, APA102, SK9822 and more (refer to the schema information).

```json
    "led": {
        "pin": 7,
        "isMono": true
    },
```

-   [ ] configure the system logging pin

```json
    "log": {
        "baud": 115200,
        "pinTX": 0
    },
```

-   [ ] configure I2C pins, add `$connector` only if there is a standardized connector

```json
    "i2c": {
        "pinSCL": 5,
        "pinSDA": 4,
    },
```

-   [ ] Update the pin map

```json
    "pins": {
        "P1": 1,
        "P11": 11,
        "P13": 13,
        "P14": 14,
        ...
    }
```

-   [ ] Update the board description
-   [ ] If available, provide a URL where the board can be purchased

Build the project to test the board definition.

```bash
npm run build
```

#### Services

Note that there is two ways of defining services in the `.board.json` file.
The ones listed under `"$services": [ ... ]` will generate `startFoo()` functions,
which need to be called for the service to be started.
The ones under `"services": [ ... ]` are always started; this is typically only
used for `power` service.

```json
    "$services": [
        {
            "service": "buzzer",
            "pin": 20,
            "name": "buzzer"
        },
        ...
    ]
```

### Flash the new configuration

The command line and Visual Studio will automatically integrate
any configuration file in the `boards/` folder.
The first time you deploy a program with a new hardware configuration, it will reset the device.

## Contributing

If you have successfully crafted a configuration for your Device and you would like to share it with other users,
you can open a GitHub Issue at https://github.com/microsoft/devicescript and attach the .JSON file. The file will
be reviewed and integrate into the built-in list.
